//
//  SPDeck.h
//  ShandongPoker
//
//  Created by Developer on 2025-01-08.
//  Copyright © 2025 ShandongPoker. All rights reserved.
//

#import <Foundation/Foundation.h>
#import "SPCard.h"

NS_ASSUME_NONNULL_BEGIN

/**
 * 扑克牌组模型
 * 管理一副完整的扑克牌，包含洗牌和发牌功能
 */
@interface SPDeck : NSObject

/// 牌组中的所有牌
@property (nonatomic, strong, readonly) NSArray<SPCard *> *allCards;

/// 当前可用的牌（未发出的牌）
@property (nonatomic, strong, readonly) NSMutableArray<SPCard *> *availableCards;

/// 已发出的牌
@property (nonatomic, strong, readonly) NSMutableArray<SPCard *> *dealtCards;

/// 牌组是否已洗牌
@property (nonatomic, assign, readonly) BOOL isShuffled;

/// 剩余牌数
@property (nonatomic, assign, readonly) NSInteger remainingCards;

/**
 * 初始化一副新的扑克牌
 * @return 扑克牌组实例
 */
- (instancetype)init;

/**
 * 初始化指定数量的扑克牌组（用于多副牌）
 * @param deckCount 牌组数量
 * @return 扑克牌组实例
 */
- (instancetype)initWithDeckCount:(NSInteger)deckCount;

/**
 * 洗牌
 * 使用Fisher-Yates算法进行随机洗牌
 */
- (void)shuffle;

/**
 * 发一张牌
 * @return 发出的牌，如果没有牌了则返回nil
 */
- (SPCard * _Nullable)dealCard;

/**
 * 发多张牌
 * @param count 要发的牌数
 * @return 发出的牌数组
 */
- (NSArray<SPCard *> *)dealCards:(NSInteger)count;

/**
 * 重置牌组
 * 将所有牌重新放回牌组，并清空已发出的牌
 */
- (void)reset;

/**
 * 检查牌组是否为空
 * @return 是否为空
 */
- (BOOL)isEmpty;

/**
 * 获取指定位置的牌（不发出）
 * @param index 牌的位置
 * @return 指定位置的牌
 */
- (SPCard * _Nullable)cardAtIndex:(NSInteger)index;

/**
 * 将牌放回牌组顶部
 * @param card 要放回的牌
 */
- (void)returnCardToTop:(SPCard *)card;

/**
 * 将牌放回牌组底部
 * @param card 要放回的牌
 */
- (void)returnCardToBottom:(SPCard *)card;

@end

NS_ASSUME_NONNULL_END 